home *** CD-ROM | disk | FTP | other *** search
/ Netware Super Library / Netware Super Library.iso / ipx_netx / ipxstuff / rkipx.doc < prev    next >
Text File  |  1992-07-06  |  15KB  |  433 lines
  1. /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
  2. /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
  3. /* HIGH-LEVEL APPLICATION PROGRAMMING IPX INTERFACE FUNCTIONS */
  4. /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
  5. /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
  6.  
  7.  
  8. /*******************************************************************/
  9. /*******************************************************************/
  10. /*
  11.   ------------------------
  12.   ------------------------
  13.   FUNCTION: IPXReceiveRT()
  14.   ------------------------
  15.   ------------------------
  16.  
  17.   Receive data into a buffer or file from a non-specified sender.
  18.  
  19.   NOTE:
  20.   The sender must know the internetwork address and socket of the
  21.   machine that is to receive its transmission(s), but the receiver
  22.   merely has to issue a LISTEN & can then receive from any sender.
  23.  
  24.   ----------
  25.   ----------
  26.   PROTOTYPE:
  27.   ----------
  28.   ----------
  29.  
  30.   unsigned IPXReceiveRT( long   *BfrLen,
  31.                          BYTE   *FileOrBfr,
  32.                          char   *SocketStr,
  33.                          void   (*RTfunc)(void) );
  34.  
  35.   ---------
  36.   ---------
  37.   INPUT(S):
  38.   ---------
  39.   ---------
  40.  
  41.   BfrLen = 0 if receiving a file
  42.              OR
  43.            the maximum # of bytes that can be stored in a given buffer
  44.  
  45.   FileOrBfr = (string) name of file (path optional) into which to write
  46.               the data that is received
  47.                 OR
  48.               pointer to given byte buffer into which to store the data
  49.               that is received
  50.  
  51.   SocketStr = 4 character hex-ASCII string of IPX Socket to
  52.               use for receiving. Note that certain NOVELL sockets
  53.               are reserved, and the caller is cautioned to use
  54.               socket numbers "40xx", e.g., "4010", "40A1", etc.
  55.  
  56.   RTfunc    = pointer to a function which is to be called during
  57.               time out loops when IPX command is pending.  Set
  58.               to NULL if you don't need this "real time" capability.
  59.  
  60.   ----------
  61.   ----------
  62.   RETURN(S):
  63.   ----------
  64.   ----------
  65.  
  66.   0x00 - GOOD_IPX_RETURN - all went well.
  67.  
  68.  
  69.   0x10 - BAD_LOCAL_TARGET - the internal IPX call to find the sender's
  70.   local target failed.  Check the global variable IPXerrno for the
  71.   specific reason, e.g.:
  72.  
  73.          0xFA - DEST_NODE_PATH_NOT_FND - the 6-byte node address
  74.                 specified in the received IPX packet parameter SrceAddr
  75.                 could not be found.  Either the packet was corrupted,
  76.                 or the sending machine with that node has died.
  77.  
  78.  
  79.   0x11 - BAD_SOCKET_PARAM - the SocketStr parameter did not consist of
  80.   a string of four hex-ascii digits.
  81.  
  82.  
  83.   0x12 - BAD_SOCKET_OPEN - the attempt to open the socket specified in
  84.   SocketStr parameter failed.  The global variable IPXerrno will contain
  85.   return code received from IPX.  It can be one of the following:
  86.  
  87.          0xFE - SOCKET_TABLE_FULL - each machine gets 20 sockets, so
  88.                 this error should never occur unless other non-"well
  89.                 behaved" IPX applications are running on the machine.
  90.  
  91.          0xFF - SOCKET_ALREADY_OPEN - it will be closed upon return,
  92.                 so try again.  It is not ignored because at the point
  93.                 of call the socket shouldn't have been open, and all
  94.                 discrepancies will be caught and reported!
  95.  
  96.  
  97.   0x20 - BAD_TX_TRY - an attempt to send a packet failed, due to
  98.   failure of either the network or the configuration of the receiving
  99.   machine.  Check the global IPXerrno to discern the problem.
  100.   It should be one of the following:
  101.  
  102.          0xFC - EVENT_CANCELED - send request was canceled by
  103.                 application due to timeout.
  104.  
  105.          0xFD - FRAGMENT_SIZE_ERROR - malformed packet size, either
  106.                 less than 30 bytes or greater than 576 bytes, or
  107.                 the event control block's Fragment Count field was 0.
  108.  
  109.          0xFE - DESTINATION_NOT_FOUND - the destination machine,
  110.                 specified in the NETADDR parameter, is not on the
  111.                 network or not powered up.
  112.  
  113.          0xFF - NETWORK_FAILURE - network or hardware failure.
  114.  
  115.  
  116.   0x21 - BAD_RETRIES - the receiver, while awaiting data from the
  117.   sending machine, has exhausted its retry number & count series.
  118.   Check IPXerrno for:
  119.  
  120.          0xFC - EVENT_CANCELED - listen request was canceled by
  121.                 application due to timeout.
  122.  
  123.          0xFD - FRAGMENT_SIZE_ERROR - either the event control block's
  124.                 Fragment Count field was 0, or the receiver's buffer
  125.                 space was too small to hold the incoming data.
  126.  
  127.          0xFF - ECB_SOCKET_NOT_OPEN - Socket for listening has not
  128.                 been opened by the application.
  129.  
  130.  
  131.   0x22 - BAD_RX_SEQ_NUM - the receiving machine has received a block
  132.   of data whose sequence number is unexpected. If this has occured,
  133.   a network failure has caused the transmission to become garbled,
  134.   or the sending machine had aborted the current send/received sequence
  135.   and restarted anew within the retry number & timeout series of the
  136.   receiving machine.  Both scenarios are highly unlikely.
  137.  
  138.  
  139.   0x30 - BAD_FILE_OPEN - the file to be received, specified by
  140.   the FileOrBfr parameter, could not be opened.  Check syntax of
  141.   ASCIIZ string to make sure path and filename are correct, and
  142.   don't forget to use double slashes in the string when specifying
  143.   a path! For example, "D:\MYPATH\MYFILE.DAT" is not a valid C
  144.   string. You must pass it as "D:\\MYPATH\\MYFILE.DAT".
  145.  
  146.  
  147.   0x31 - BAD_FILE_WRITE - problem writing to the file specified in the
  148.   parameter FileOrBfr, even though the file was successfully opened.
  149.   This should never occur, barring disk failure or some strange
  150.   interaction between the caller's program and other programs running
  151.   as background processes or TSR's.
  152.  
  153.  
  154.   0xBB - USER_TERMINATED - the user has chosen to abort the application
  155.   by hitting the two SHIFT keys & an ALT key during a send/receive sequence.
  156.  
  157.  
  158.   0xDD - IPX_NOT_PRESENT - IPX API interface was not detected. Make
  159.   sure NOVELL's IPX.COM or equivalent has been run before attempting to
  160.   access IPX functions.
  161.  
  162.  
  163.   -------------------------
  164.   -------------------------
  165.   APPLICATION CODE EXAMPLE:
  166.   -------------------------
  167.   -------------------------
  168.  
  169.   #include "rkipx.h"
  170.  
  171.   #define RXSOCKET  "4050"
  172.   #define RXBFRSIZE  8192
  173.  
  174.   int main( void )
  175.   {
  176.   unsigned rc;
  177.   long     len;
  178.   BYTE     *RxBfr;
  179.  
  180.   // receiving a file
  181.   len = 0;
  182.   rc = IPXReceiveRT( &len, "RXDATA.DAT", RXSOCKET, NULL );
  183.   if ( rc != GOOD_IPX_RETURN )
  184.      {
  185.      printf( "FUNCTION ERROR: %02X  IPX ERROR: %02X", rc, IPXerrno );
  186.      // take appropriate error action here
  187.      return( -1 );
  188.      }
  189.  
  190.   // receiving a buffer
  191.   RxBfr = calloc( 1, RXBFRSIZE );
  192.   if ( !RxBfr )
  193.      {
  194.      printf( "MEMORY ALLOCATION FAILURE!" );
  195.      return( -1 );
  196.      }
  197.  
  198.   len = RXBFRSIZE;
  199.   rc = IPXReceiveRT( &len, RxBfr, RXSOCKET, NULL );
  200.   if ( rc != GOOD_IPX_RETURN )
  201.      {
  202.      printf( "FUNCTION ERROR: %02X  IPX ERROR: %02X", rc, IPXerrno );
  203.      // take appropriate error action here
  204.      return( -1 );
  205.      }
  206.  
  207.   return( 0 );
  208.   }
  209.  
  210. */
  211. /*******************************************************************/
  212. /*******************************************************************/
  213. /*
  214.   ---------------------
  215.   ---------------------
  216.   FUNCTION: IPXSendRT()
  217.   ---------------------
  218.   ---------------------
  219.  
  220.   Send a file or buffer to specified destination machine
  221.  
  222.   ----------
  223.   ----------
  224.   PROTOTYPE:
  225.   ----------
  226.   ----------
  227.  
  228.   unsigned IPXSendRT( long     *BfrLen,
  229.                       BYTE     *FileOrBfr,
  230.                       char     *SocketStr,
  231.                       NETADDR  *Destination,
  232.                       void     (*RTfunc)(void) );
  233.  
  234.   ---------
  235.   ---------
  236.   INPUT(S):
  237.   ---------
  238.   ---------
  239.  
  240.   BfrLen = 0 if sending a file
  241.              OR
  242.            the # of bytes to send from a given byte buffer
  243.  
  244.   FileOrBfr = (string) name of file (path optional) to send
  245.                 OR
  246.               pointer to given byte buffer from which to send data
  247.  
  248.   SocketStr = 4 character hex-ASCII string of IPX Socket to
  249.               use for sending. Note that certain NOVELL sockets
  250.               are reserved, and the caller is cautioned to use
  251.               socket numbers "40xx", e.g., "4010", "40A1", etc.
  252.  
  253.   Destination = structure containing Network Address, Node
  254.                 Address, and receiving socket number of the
  255.                 machine that is to receive the file/buffer data.
  256.                 See IPX.H for structure layout; if needed, use
  257.                 function xatoxb() for converting hex-ascii
  258.                 strings to hex-binary bytes.
  259.  
  260.   RTfunc    = pointer to a function which is to be called during
  261.               time out loops when IPX command is pending.  Set
  262.               to NULL if you don't need this "real time" capability.
  263.  
  264.   ----------
  265.   ----------
  266.   RETURN(S):
  267.   ----------
  268.   ----------
  269.  
  270.   0x00 - GOOD_IPX_RETURN - all went well.
  271.  
  272.  
  273.   0x10 - BAD_LOCAL_TARGET - the internal IPX call to find the receiver's
  274.   local target failed.  Check the global variable IPXerrno for the
  275.   specific reason, e.g.:
  276.  
  277.          0xFA - DEST_NODE_PATH_NOT_FND - the 6-byte node address
  278.                 specified in the passed parameter Destination.INA.Node
  279.                 could not be found.  Either the node is non-extant, or
  280.                 the machine with that node is not powered on.
  281.  
  282.  
  283.   0x11 - BAD_SOCKET_PARAM - the SocketStr parameter did not consist of
  284.   a string of four hex-ascii digits.
  285.  
  286.  
  287.   0x12 - BAD_SOCKET_OPEN - the attempt to open the socket specified in
  288.   SocketStr parameter failed.  The global variable IPXerrno will contain
  289.   return code received from IPX.  It can be one of the following:
  290.  
  291.          0xFE - SOCKET_TABLE_FULL - each machine gets 20 sockets, so
  292.                 this error should never occur unless other non-"well
  293.                 behaved" IPX applications are running on the machine.
  294.  
  295.          0xFF - SOCKET_ALREADY_OPEN - it will be closed upon return,
  296.                 so try again.  It is not ignored because at the point
  297.                 of call the socket shouldn't have been open, and all
  298.                 discrepancies will be caught and reported!
  299.  
  300.  
  301.   0x20 - BAD_TX_TRY -  the attempt to send an IPX packet failed due to
  302.   a problem of either the network or the configuration of the sending
  303.   machine. Check the global IPXerrno to discern the problem.  It should
  304.   be one of the following:
  305.  
  306.          0xFC - EVENT_CANCELED - send request was canceled by
  307.                 application due to timeout.
  308.  
  309.          0xFD - FRAGMENT_SIZE_ERROR - malformed packet size, either
  310.                 less than 30 bytes or greater than 576 bytes, or
  311.                 the event control block's Fragment Count field was 0.
  312.  
  313.          0xFE - DESTINATION_NOT_FOUND - the destination machine,
  314.                 specified in the NETADDR parameter, is not on the
  315.                 network or not powered up.
  316.  
  317.          0xFF - NETWORK_FAILURE - network or hardware failure.
  318.  
  319.  
  320.   0x21 - BAD_RETRIES - the sender has been awaiting an acknowledgement
  321.   from the receiver for most recently sent data, and has exhausted its
  322.   retry number & count series.  Check IPXerrno for:
  323.  
  324.          0xFC - EVENT_CANCELED - listen request was canceled by
  325.                 application due to timeout.
  326.  
  327.          0xFD - FRAGMENT_SIZE_ERROR - either the event control block's
  328.                 Fragment Count field was 0, or the receiver's buffer
  329.                 space was too small to hold the incoming data.
  330.  
  331.          0xFF - ECB_SOCKET_NOT_OPEN - Socket for listening has not
  332.                 been opened by the application.
  333.  
  334.  
  335.   0x22 - BAD_RX_SEQ_NUM - the destination machine has transmitted an
  336.   acknowledgement to received data, but the sequence number does not
  337.   match the sequence number of the data that the sender transmitted.
  338.   If this problem occurs, either a network failure has caused the
  339.   transmission to become garbled, or the destination machine had
  340.   aborted the current send/received sequence and restarted anew
  341.   within the retry number & timeout series of the sender.
  342.   Both scenarios are highly unlikely.
  343.  
  344.   0x23 - BAD_RX_SRCE_ADDR - the sending machine received a transmission
  345.   from a machine other than the expected receiver of the original trans-
  346.   mission.  This should never occur, due to the fact that the sender
  347.   socket should be known at this point only to the receiver of the
  348.   message that the sender transmitted.  If other machines transmitting
  349.   on the network are getting through to another sender unexpectedly, then
  350.   some application software debugging is in order, or special TSR programs
  351.   are running, the behavior of which should be monitored more stringently.
  352.  
  353.  
  354.   0x30 - BAD_FILE_OPEN - the file to be transmitted, specified by
  355.   the FileOrBfr parameter, could not be opened.  Check syntax of
  356.   ASCIIZ string to make sure path and filename are correct, and
  357.   don't forget to use double slashes in the string when specifying
  358.   a path! For example, "D:\MYPATH\MYFILE.DAT" is not a valid C
  359.   string. You must pass it as "D:\\MYPATH\\MYFILE.DAT".
  360.  
  361.  
  362.   0x32 - BAD_FILE_READ - problem reading the file specified in the
  363.   parameter FileOrBfr, even though the file was successfully opened.
  364.   This should never occur, barring disk failure or some strange
  365.   interaction between the caller's program and other programs running
  366.   as background processes or TSR's.
  367.  
  368.  
  369.   0xBB - USER_TERMINATED - the user has chosen to abort the application
  370.   by hitting the two SHIFT keys & an ALT key during a send/receive sequence.
  371.  
  372.  
  373.   0xDD - IPX_NOT_PRESENT - IPX API interface was not detected. Make
  374.   sure NOVELL's IPX.COM or equivalent has been run before attempting to
  375.   access IPX functions.
  376.  
  377.  
  378.   -------------------------
  379.   -------------------------
  380.   APPLICATION CODE EXAMPLE:
  381.   -------------------------
  382.   -------------------------
  383.  
  384.   #include "rkipx.h"
  385.  
  386.   #define TXSOCKET  "4050"
  387.   #define TXBFRSIZE  8192
  388.  
  389.   int main( void )
  390.   {
  391.   NETADDR  na;
  392.   unsigned rc;
  393.   long     len;
  394.   BYTE     *TxBfr;
  395.  
  396.   // hard-coded example of internetwork address of destination machine
  397.   xatoxb( na.INA.Network, "01234567" );
  398.   xatoxb( na.INA.Node, "0123456789AB" );
  399.   xatoxb( na.Socket, "4010" );
  400.  
  401.   // sending a file
  402.   len = 0;
  403.   rc = IPXSendRT( &len, "TXDATA.DAT", TXSOCKET, &na, NULL );
  404.   if ( rc != GOOD_IPX_RETURN )
  405.      {
  406.      // take appropriate error action here
  407.      return( -1 );
  408.      }
  409.  
  410.   // sending a buffer
  411.   TxBfr = calloc( 1, TXBFRSIZE );
  412.   if ( !TxBfr )
  413.      {
  414.      printf( "MEMORY ALLOCATION FAILURE!" );
  415.      return( -1 );
  416.      }
  417.  
  418.   len = TXBFRSIZE;
  419.   rc = IPXSendRT( &len, TxBfr, TXSOCKET, &na, NULL );
  420.   if ( rc != GOOD_IPX_RETURN )
  421.      {
  422.      printf( "FUNCTION ERROR: %02X  IPX ERROR: %02X", rc, IPXerrno );
  423.      // take appropriate error action here
  424.      return( -1 );
  425.      }
  426.  
  427.   return( 0 );
  428.   }
  429.  
  430. */
  431. /*******************************************************************/
  432. /*******************************************************************/
  433.